Streams can be classified into two types: text streams and binary streams. Text streams are interpreted, with a maximum length of 255 characters. With text streams, carriage return/line feed combinations are translated to the newline \n character and vice versa. Binary streams are uninterpreted and are treated one byte at a time with no translation of characters. Typically, a text stream would be used for reading and writing standard text files, printing output to the screen or printer, or receiving input from the keyboard.
A binary text stream would typically be used for reading and writing binary files such as graphics or word processing documents, reading mouse input, or reading and writing to the modem.

Stream functions such as fread() and fwrite() are buffered and are more efficient when reading and writing text or binary data to files. You generally gain better performance by using stream functions rather than their unbuffered low-level counterparts such as read() and write().
In multiuser environments, however, when files are typically shared and portions of files are continuously being locked, read from, written to, and unlocked, the stream functions do not perform as well as the low- level functions. This is because it is hard to buffer a shared file whose contents are constantly changing.
Generally, you should always use buffered stream functions when accessing nonshared files, and you should always use the low-level functions when accessing shared files.

Unfortunately, there is no built-in function provided in the C language such as dir_list() that would easily provide you with a list of all files in a particular directory. By utilizing some of C's built-in directory functions, however, you can write your own dir_list() function.
First of all, the include file dos.h defines a structure named find_t, which represents the structure of the DOS file entry block. This structure holds the name, time, date, size, and attributes of a file. Second, your C compiler library contains the functions _dos_findfirst() and _dos_findnext(), which can be used to find the first or next file in a directory.
The _dos_findfirst() function requires three arguments. The first argument is the file mask for the directory list. A mask of *.* would be used to list all files in the directory. The second argument is an attribute mask, defining which file attributes to search for. For instance, you might want to list only files with the Hidden or Directory attributes. The last argument of the _dos_findfirst() function is a pointer to the variable that is to hold the directory information (the find_t structure variable).
The second function you will use is the _dos_findnext() function. Its only argument is a pointer to the find_tstructure variable that you used in the _dos_findfirst() function. Using these two functions and the find_tstructure, you can iterate through the directory on a disk and list each file in the directory. Here is the code to perform this task:
#include
#include
#include
#include
#include
#include
typedef struct find_t FILE_BLOCK;
void main(void);
void main(void)
{
FILE_BLOCK f_block; /* Define the find_t structure variable */
int ret_code; /* Define a variable to store the return codes */
printf("\nDirectory listing of all files in this directory:\n\n");
/* Use the "*.*" file mask and the 0xFF attribute mask to list
all files in the directory, including system files, hidden
files, and subdirectory names. */
ret_code = _dos_findfirst("*.*", 0xFF, &f_block);
/* The _dos_findfirst() function returns a 0 when it is successful
and has found a valid filename in the directory. */
while (ret_code == 0)
{
/* Print the file's name */
printf("%-12s\n", f_block.name);
/* Use the _dos_findnext() function to look
for the next file in the directory. */
ret_code = _dos_findnext(&f_block);
}
printf("\nEnd of directory listing.\n");
}

A file's date and time are stored in the find_t structure returned from the _dos_findfirst() and_dos_findnext() functions.
The date and time stamp of the file is stored in the find_t.wr_date and find_t.wr_time structure members. The file date is stored in a two-byte unsigned integer as shown here:
Element Offset Range
Seconds - 5 bits - 0-9 (multiply by 2 to get the seconds value)
Minutes - 6 bits - 0-59
Hours - 5 bits - 0-23
Similarly, the file time is stored in a two-byte unsigned integer, as shown here:
Element Offset Range
Day - 5 bits - 1-31
Month - 4 bits - 1-12
Year - 7 bits - 0-127 (add the value "1980" to get the year value)
Because DOS stores a file's seconds in two-second intervals, only the values 0 to 29 are needed. You simply multiply the value by 2 to get the file's true seconds value. Also, because DOS came into existence in 1980, no files can have a time stamp prior to that year. Therefore, you must add the value "1980" to get the file's true year value.
The following example program shows how you can get a directory listing along with each file's date and time stamp:
#include
#include
#include
#include
#include
#include
typedef struct find_t FILE_BLOCK;
void main(void);
void main(void)
{
FILE_BLOCK f_block; /* Define the find_t structure variable */
int ret_code; /* Define a variable to store return codes */
int hour; /* We're going to use a 12-hour clock! */
char* am_pm; /* Used to print "am" or "pm" */
printf("\nDirectory listing of all files in this directory:\n\n");
/* Use the "*.*" file mask and the 0xFF attribute mask to list
all files in the directory, including system files, hidden
files, and subdirectory names. */
ret_code = _dos_findfirst("*.*", 0xFF, &f_block);
/* The _dos_findfirst() function returns a 0 when it is successful
and has found a valid filename in the directory. */
while (ret_code == 0)
{
/* Convert from a 24-hour format to a 12-hour format. */
hour = (f_block.wr_time >> 11);
if (hour > 12)
{
hour = hour - 12;
am_pm = "pm";
}
else
am_pm = "am";
/* Print the file's name, date stamp, and time stamp. */
printf("%-12s %02d/%02d/%4d %02d:%02d:%02d %s\n",
f_block.name, /* name */
(f_block.wr_date >> 5) & 0x0F, /* month */
(f_block.wr_date) & 0x1F, /* day */
(f_block.wr_date >> 9) + 1980, /* year */
hour, /* hour */
(f_block.wr_time >> 5) & 0x3F, /* minute */
(f_block.wr_time & 0x1F) * 2, /* seconds */
am_pm);
/* Use the _dos_findnext() function to look
for the next file in the directory. */
ret_code = _dos_findnext(&f_block);
}
printf("\nEnd of directory listing.\n");
}
Notice that a lot of bit-shifting and bit-manipulating had to be done to get the elements of the time variable and the elements of the date variable. If you happen to suffer from bitshiftophobia (fear of shifting bits), you can optionally code the preceding example by forming a union between the find_t structure and your own user-defined structure, such as this:
/* This is the find_t structure as defined by ANSI C. */
struct find_t
{
char reserved[21];
char attrib;
unsigned wr_time;
unsigned wr_date;
long size;
char name[13];
}
/* This is a custom find_t structure where we
separate out the bits used for date and time. */
struct my_find_t
{
char reserved[21];
char attrib;
unsigned seconds:5;
unsigned minutes:6;
unsigned hours:5;
unsigned day:5;
unsigned month:4;
unsigned year:7;
long size;
char name[13];
}
/* Now, create a union between these two structures
so that we can more easily access the elements of
wr_date and wr_time. */
union file_info
{
struct find_t ft;
struct my_find_t mft;
}
Using the preceding technique, instead of using bit-shifting and bit-manipulating, you can now extract date and time elements like this:
...
file_info my_file;
...
printf("%-12s %02d/%02d/%4d %02d:%02d:%02d %s\n",
my_file.mft.name, /* name */
my_file.mft.month, /* month */
my_file.mft.day, /* day */
(my_file.mft.year + 1980), /* year */
my_file.mft.hours, /* hour */
my_file.mft.minutes, /* minute */
(my_file.mft.seconds * 2), /* seconds */
am_pm);

When you are sorting the filenames in a directory, the one-at-a-time approach does not work. You need some way to store the filenames and then sort them when all filenames have been obtained. This task can be accomplished by creating an array of pointers to find_t structures for each filename that is found. As each filename is found in the directory, memory is allocated to hold the find_t entry for that file. When all filenames have been found, the qsort() function is used to sort the array of find_t structures by filename.
The qsort() function can be found in your compiler's library. This function takes four parameters: a pointer to the array you are sorting, the number of elements to sort, the size of each element, and a pointer to a function that compares two elements of the array you are sorting. The comparison function is a user-defined function that you supply. It returns a value less than zero if the first element is less than the second element, greater than zero if the first element is greater than the second element, or zero if the two elements are equal. Consider the following example:
#include
#include
#include
#include
#include
#include
typedef struct find_t FILE_BLOCK;
int sort_files(FILE_BLOCK**, FILE_BLOCK**);
void main(void);
void main(void)
{
FILE_BLOCK f_block; /* Define the find_t structure variable */
int ret_code; /* Define a variable to store the return
codes */
FILE_BLOCK** file_list; /* Used to sort the files */
int file_count; /* Used to count the files */
int x; /* Counter variable */
file_count = -1;
/* Allocate room to hold up to 512 directory entries. */
file_list = (FILE_BLOCK**) malloc(sizeof(FILE_BLOCK*) * 512);
printf("\nDirectory listing of all files in this directory:\n\n");
/* Use the "*.*" file mask and the 0xFF attribute mask to list
all files in the directory, including system files, hidden
files, and subdirectory names. */
ret_code = _dos_findfirst("*.*", 0xFF, &f_block);
/* The _dos_findfirst() function returns a 0 when it is successful
and has found a valid filename in the directory. */
while (ret_code == 0 && file_count < 512)
{
/* Add this filename to the file list */
file_list[++file_count] =
(FILE_BLOCK*) malloc(sizeof(FILE_BLOCK));
*file_list[file_count] = f_block;
/* Use the _dos_findnext() function to look
for the next file in the directory. */
ret_code = _dos_findnext(&f_block);
}
/* Sort the files */
qsort(file_list, file_count, sizeof(FILE_BLOCK*), sort_files);
/* Now, iterate through the sorted array of filenames and
print each entry. */
for (x=0; x {
printf("%-12s\n", file_list[x]->name);
}
printf("\nEnd of directory listing.\n");
}
int sort_files(FILE_BLOCK** a, FILE_BLOCK** b)
{
return (strcmp((*a)->name, (*b)->name));
}
This example uses the user-defined function named sort_files() to compare two filenames and return the appropriate value based on the return value from the standard C library function strcmp(). Using this same technique, you can easily modify the program to sort by date, time, extension, or size by changing the element on which the sort_files() function operates.